=item I<pause> <DomId>
Pause a domain. When in a paused state the domain will still consume
-allocated resources like memory, but will not be eligible for
+allocated resources such as memory, but will not be eligible for
scheduling by the Xen hypervisor.
=item I<reboot> [Options] <DomId>
=item I<restore> <File>
-Create a domain from saved state File.
+Build a domain from an B<xm save> state file. See I<save> for more info.
=item I<save> <DomId> <File>
-Save domain state to File. Saves domain configuration to File as well.
+Saves a running domain to a state file so that it can be restored
+later. Once saved, the domain will no longer be running on the
+system, thus the memory allocated for the domain will be free for
+other domains to use. B<xm restore> restores from this state file.
+
+This is roughly equivalent to doing a hibernate on a running computer,
+with all the same limitations. Open network connections may be
+severed upon restore, as TCP timeouts may have expired.
=item I<shutdown> [Options] <DomId>
-Shutdown a domain.
+Gracefully shuts down a domain. This coordinates with the domain OS
+to perform graceful shutdown, so there is no guaruntee that it will
+succeed, and may take a variable length of time depending on what
+services must be shutdown in the domain. The command returns
+immediately after signally the domain unless that I<-w> flag is used.
+
+The behavior of what happens to a domain when it reboots is set by the
+B<on_shutdown> parameter of the xmdomain.cfg file when the domain was
+created.
+
+B<OPTIONS>
=over 4
-Additional Options:
+=item I<-a>
+
+Shutdown B<all> domains. Often used when doing a complete shutdown of
+a Xen system.
- -a, --all Shutdown all domains.
- -H, --halt Shutdown domain without reboot.
- -R, --reboot Shutdown and reboot domain.
- -w, --wait Wait for shutdown to complete.
+=item I<-w>
+
+Wait for the domain to complete shutdown before returning.
=back
=item I<sysrq> <DomId> <letter>
-Send a sysrq to a domain.
+Send a I<Magic System Request> signal to the domain. For more
+information on available magic sys req operations, see sysrq.txt in
+your Linux Kernel sources.
=item I<unpause> <DomId>
-Unpause a paused domain.
+Moves a domain out of the paused state. This will allow a previously
+paused domain to now be eligible for scheduling by the Xen hypervisor.
+
+=item I<set-vcpus> <DomId> <VCPUCount>
-=item I<set-vcpus> <DomId> <VCPUs>
+Enables the I<VCPUcount> virtual CPUs for the domain in question.
+Like mem-set, this command can only allocate up to the maximum virtual
+CPU count configured at boot for the domain.
-Enable a specific number of VCPUs for a domain. Subcommand only enables or disables already configured VCPUs for domain.
+If the VCPUcount is smaller than the current number of active VCPUs,
+the highest number VCPUs will be hotplug removed. This may be
+important for pinning purposes.
+
+Attempting to set-vcpus to a number larger than the initially
+configured VCPU count is an error. Trying to set-vcpus to < 1 will be
+quietly ignored.
=item I<vpcu-list> [DomID]
-Lists VCPU information for a specific domain or all domains if DomID not given.
+Lists VCPU information for a specific domain. If no domain is
+specified, VCPU information for all domains will be provided.
=item I<vcpu-pin> <DomId> <VCPU> <CPUs>
-Sets VCPU to only run on specific CPUs.
+Pins the the VCPU to only run on the specific CPUs.
+
+Normally VCPUs can float between available CPUs whenever Xen deems a
+different run state is appropriate. Pinning can be used to restrict
+this, by ensuring certain VCPUs can only run on certain physical
+CPUs.
=back
=item I<dmesg> [OPTION]
-Read or clear Xen's message buffer. The buffer contains Xen boot, warning, and error messages.
+Reads the Xen message buffer, similar to dmesg on a Linux system. The
+buffer contains informational, warning, and error messages created
+during Xen's boot process. If you are having problems with Xen, this
+is one of the first places to look as part of problem determination.
+
+B<OPTIONS>
=over 4
-Additional Option:
+=item I<-c, --clear>
- -c, --clear Clears Xen's message buffer.
+Clears Xen's message buffer.
=back
=item I<info>
-Get information about Xen host.
+Print information about the Xen host in I<name : value> format. When
+reporting a Xen bug, please provide this information as part of the
+bug report.
+
+Sample xen domain info looks as follows:
+
+ system : Linux
+ host : talon
+ release : 2.6.12.6-xen0
+ version : #1 Mon Nov 14 14:26:26 EST 2005
+ machine : i686
+ nr_cpus : 2
+ nr_nodes : 1
+ sockets_per_node : 2
+ cores_per_socket : 1
+ threads_per_core : 1
+ cpu_mhz : 696
+ hw_caps : 0383fbff:00000000:00000000:00000040
+ memory : 767
+ free_memory : 37
+ xen_major : 3
+ xen_minor : 0
+ xen_extra : -devel
+ xen_caps : xen-3.0-x86_32
+ xen_params : virt_start=0xfc000000
+ xen_changeset : Mon Nov 14 18:13:38 2005 +0100 7793:090e44133d40
+ cc_compiler : gcc version 3.4.3 (Mandrakelinux 10.2 3.4.3-7mdk)
+ cc_compile_by : sdague
+ cc_compile_domain : (none)
+ cc_compile_date : Mon Nov 14 14:16:48 EST 2005
+
+B<FIELDS>
+
+=over 4
+
+Not all fields will be explained here, but some of the less obvious
+ones deserve explanation:
+
+=item I<hw_caps>
+
+A vector showing what hardware capabilities are supported by your
+processor. This is equivalent to, though more cryptic, the flags
+field in /proc/cpuinfo on a normal Linux machine.
+
+=item I<free_memory>
+
+Available memory (in MB) not allocated to Xen, or any other Domains.
+
+=item I<xen_caps>
+
+The xen version, architecture. Architecture values can be one of:
+x86_32, x86_32p (i.e. PAE enabled), x86_64, ia64.
+
+=item I<xen_changeset>
+
+The xen mercurial changeset id. Very useful for determining exactly
+what version of code your Xen system was built from.
+
+=back
=item I<log>
-Print B<xend> log.
+Print out the B<xend> log. This log file can be found in
+/var/log/xend.log.
=item I<top>
-Monitor system and domains in real-time.
+Executes the xentop command, which provides real time monitoring of
+domains. Xentop is a curses interface, and reasonably self
+explainitory.
=back
=head1 SCHEDULER SUBCOMMANDS
+FIXME: we really need a scheduler expert to write up this section.
+
=over 4
=item I<sched-bvt> <Parameters>
-Set Borrowed Virtual Time (BVT) scheduler parameters. There are five parameters, which are given in order below.
+Set Borrowed Virtual Time (BVT) scheduler parameters. There are five
+parameters, which are given in order below.
=over 4
=item I<sched-bvt-ctxallow> <Allow>
-Sets the BVT scheduler's context switch allowance. Allow is the minimum time slice allowed to run before being pre-empted.
+Sets the BVT scheduler's context switch allowance. Allow is the
+minimum time slice allowed to run before being pre-empted.
=item I<sched-sedf> <Parameters>
-Set simple sEDF scheduler parameters. Use the following parametersin order.
+Set simple sEDF scheduler parameters. Use the following parametersin
+order.
=over 4
=head1 VIRTUAL DEVICE COMMANDS
+Most virtual devices can be added and removed while guests are
+running. The effect to the guest OS is much the same as any hotplug
+event.
+
=over 4
=item I<block-attach <DomId> <BackDev> <FrontDev> <Mode> [BackDomId]
-Create a new virtual block device.
+Create a new virtual block device
=item I<block-detach> <DomId> <DevId>
-Destroy a domain's virtual block device. DevId may either be a device ID or the device name as mounted in the guest.
+Destroy a domain's virtual block device. DevId may either be a device
+ID or the device name as mounted in the guest.
=item I<block-list> <DomId>
projects / xen.git / commitdiff